home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 3 / Cream of the Crop 3.iso / sound / ptmid.zip / PTMID.DOC < prev    next >
Text File  |  1994-01-06  |  11KB  |  240 lines
  1. NAME
  2.  
  3.      ptmid - Converts MIDI music files to Protracker files (ver 0.1)
  4.  
  5.  
  6. SYNOPSIS
  7.  
  8.      ptmid [-cFile] [-dChannel] [-fFrac] [-q] infile[.mid]
  9.           [outfile[.mod]]
  10.  
  11.  
  12. DESCRIPTION
  13.  
  14.      Ptmid will take either standard MIDI format 0 or format 1 files and
  15.      convert them into various Protracker-type files. MIDI files are
  16.      industry standard, but need some sort of sequencer to be played, as
  17.      there can be near infinite simultaneous notes (though about 20 is a
  18.      standard maximum). Protracker files are 4 channel (though 6 and 8
  19.      channel varieties are supported) files, but have a bank of
  20.      digitized instruments included, so reasonable quality sound is
  21.      produced given limited hardware.
  22.  
  23.      The differences between MIDI (extension .mid) and Protracker
  24.      (extension .mod) formats are more than superficial, and a fair bit
  25.      of information is needed to be able perform the conversion - most
  26.      of this is held in the configuration file: ptmid.cfg
  27.  
  28.      The format of ptmid.cfg is fairly simple: Any line beginning with a
  29.      hash (#) is ignored, other lines contain configuration info. The
  30.      first word on a line specifies what sort of information (and
  31.      sometimes only one word is needed), anything following this word is
  32.      used as supplementary information and depends of the sort of option
  33.      specified by the first word. Here are a list of options and
  34.      descriptions:
  35.  
  36.           def, xx, or dxx (where xx is a number): These options supply
  37.           information on what samples (digitized instruments) should be
  38.           allocated to what MIDI instrument numbers. "def" is the
  39.           default non-percussion instrument, and must always be
  40.           specified. "xx" is a specific MIDI instrument. "dxx" is a
  41.           specific MIDI percussion instrument (non-specified percussion
  42.           instruments are not converted). After the option name are the
  43.           filenames of the samples that can be used to represent the
  44.           instrument. Multiple filenames may be specified, except for
  45.           percussion instruments which may only have one.
  46.  
  47.           sample: This option is followed by the filename of a sample
  48.           and its pitch when played at 8287 Hz (or for percussion
  49.           samples, the note to play). Optionally, it can then be
  50.           followed by a loop-start offset and a loop-length (in that
  51.           order), specified in words (1 word = 2 bytes). After a sample
  52.           is played it will stop if no loop information is given,
  53.           otherwise it will start looping at the loop-start address and
  54.           continue for the length of the loop-length (looping continues
  55.           indefinitely). Pitch is given by a note letter (A, B, C,
  56.           etc.), optionally followed by a sharp sign (#), followed by
  57.           the octave of the note (.. 0, 1, 2 ..) where middle C is in
  58.           octave 2 (an octave ranges from the C in that octave to the B#
  59.           above). A sample must be specified for EVERY filename given in
  60.           one of the above options (def, xx, dxx).
  61.  
  62.           drumch: The percussion channel is assumed to be 10, but some
  63.           MIDI devices assume it is elsewhere, and so Ptmid must know
  64.           what channel it will be to perform a correct conversion.
  65.           Following the option name is a number which is the percussion
  66.           channel. Common values are 10 and 16.
  67.  
  68.           fract: Ptmid quantizes (that is, groups notes to the closest
  69.           note) MIDI files duration conversion, and so must know what
  70.           the smallest type of note is. Following the option name is a
  71.           number (possibly with a suffix of "t") which represents a type
  72.           of note - this is the quantize fraction. Valid fractions are
  73.           of the form: 4, 4t, 8, 8t, 16, 16t, etc. where 4 means a
  74.           quarter note (crotchet), 4t means a triplet, 8 means an
  75.           eighth-note (quaver), 8t means quaver-triplets, etc. It
  76.           usually can't hurt to give a smaller note (larger value),
  77.           though it uses up more memory, but the critical part is
  78.           knowing if a triplet note is needed. If not specified, the
  79.           fraction is assumed to be 16. This option can be overridden
  80.           with the similar option specified on the command line.
  81.  
  82.           patchan: To aid in supporting multiple Protracker-type formats
  83.           this option allows you to specify the number of channels (max.
  84.           of 8). Following the option name is the number of channels. If
  85.           not specified, it defaults to 4.
  86.  
  87.           patmax: Following this option is the maximum number of
  88.           patterns. It will default to 64, and has a maximum of 128. You
  89.           should only need to specify a larger value if you get a
  90.           warning that during conversion, Ptmid has reached the pattern
  91.           maximum.
  92.  
  93.           formid: Following this option is a 4-letter string which is
  94.           used as an ID by the program which plays Protracker files (a
  95.           tracker) to determine the above 2 values. It defaults to
  96.           "M.K.". Common combinations of these 3 options are:
  97.                ptchan    patmax    formid
  98.                  4         64       M.K.
  99.                  4        128       M!K!
  100.                  6         64       6CHN
  101.                  8         64       8CHN
  102.           (These formid values are supported by the DMP tracker.)
  103.  
  104.           extend: If this option is present, then an extended range of
  105.           notes is allowed during conversion. Usually there is a 3
  106.           octave range, but since MIDI allows a 9 octave range
  107.           converted files can sound wrong. With an extended range, 5
  108.           octaves are supported, but you need special trackers for this
  109.           (the tracker DMP is one example). The best solution for this
  110.           problem is to use multiple samples, each of which is digitized
  111.           an octave apart, and specify all of them for an instrument.
  112.  
  113.           nocopy: This option will stop copyrighted MIDI files being
  114.           converted if it is present. Since MIDI files support a
  115.           copyright notice as part of their official format, I thought
  116.           that this would be a good option for the fascist-minded.
  117.  
  118.      Options in the configuration file may be given in any order, and
  119.      are all optional except for "def" and "sample".
  120.      DMP is written by Otto Crons (no relation :).
  121.  
  122.      How Ptmid works. Well.. Firstly it reads the entire MIDI file
  123.      (except hardware dependent effects) into memory as a series of
  124.      chords, quantizing as it goes. Then it scans the its copy of the
  125.      tune and allocates samples to each note, and converts volumes etc.
  126.      After doing this it writes it to a Protracker format file (MOD
  127.      file), if there are more notes than channels then it picks what it
  128.      guesses to be shorter notes rather than longer notes. The reason
  129.      behind this is that shorter notes allow more notes to come later,
  130.      freeing up channels sooner.. okay, so it's not a very good reason.
  131.  
  132.      I originally wanted to do "channel pruning" before the writing
  133.      stage occurred, but yes I'm slack and wanted to get a working copy
  134.      released. Anyway, this means there is a bit of inelegancy: samples
  135.      may be allocated to notes, but those notes are pruned later on and
  136.      are never played, leaving redundant samples.
  137.  
  138.  
  139. OPTIONS
  140.  
  141.      cFile     "File" is the filename of the configuration file. If not
  142.                given will default to "ptmid.cfg". See above for format
  143.                of the configuration file.
  144.  
  145.      dChannel  "Channel" is a number from 1 to 16. This is the channel
  146.                used for percussion instruments. See "drumch" option
  147.                above.
  148.  
  149.      fFrac     "Frac" is a quantize fraction. It can take values of the
  150.                form: 4, 4t, 8, 8t, etc. See the "fract" option above,
  151.                which this option overrides.
  152.  
  153.      q         Enables quiet-mode. Only error messages are sent (to
  154.                stderr).
  155.  
  156. EXAMPLES
  157.  
  158.      prompt> ptmid -f32t jazz3
  159.  
  160.      ptmid ver 0.1: Converting 'jazz3.mid' to 'jazz3.mod'
  161.      Ticks to quantize: 16
  162.      Number of tracks: 6
  163.      Analyzing..
  164.      Writing..
  165.      Writing 6 samples: ......
  166.      Done.
  167.  
  168.      prompt>
  169.  
  170. DIAGNOSTICS
  171.  
  172.      The following errors terminate immediately and return an exit code
  173.      of 1.
  174.  
  175.      Cannot find config file: xxxx
  176.  
  177.           Either ptmid.cfg cannot be found (eg. not in current
  178.           directory) or the file specified with the option -c has been
  179.           incorrectly given.
  180.  
  181.      Error in config file: line xx
  182.  
  183.           Something is wrong with the config file on that line. Check
  184.           the above formats for options.
  185.  
  186.      No default instrument defined in config file
  187.  
  188.           Make sure there is a "def" option in the config file.
  189.  
  190.      No sample definitions found in config file
  191.  
  192.           Likewise, make sure there is a "sample" option.
  193.  
  194.      Invalid quantize fraction - using default
  195.  
  196.           You have incorrectly specified the fraction in the -f option.
  197.           Make sure it is of a similar form to: 4, 4t, 8, 8t, etc. Ptmid
  198.           is going ahead, but using the value 16.
  199.  
  200.      Cannot access file: xxxx
  201.  
  202.           The MIDI file you have specified cannot be opened for reading.
  203.  
  204.      Not a legal MIDI file: xxxx
  205.  
  206.           There is something wrong with the MIDI file you have
  207.           specified (like it isn't one), or there is a copyright notice
  208.           in it and the NOCOPY option has been enabled (see above).
  209.  
  210.      Cannot create file: xxxx
  211.  
  212.           The Protracker file cannot be opened for writing.
  213.  
  214.      No more files can be opened
  215.  
  216.           While reading the MIDI file, Ptmid has run out of file handles
  217.           (there should be at least 1 more than the number of tracks in
  218.           the file), so if you can increase them, please do.
  219.  
  220.      Cannot allocate any more memory
  221.  
  222.           Nasty. Try recompiling the sources to use a bigger memory
  223.           model, install more memory (probably make no difference),
  224.           switch to a different operating system, or wait until other
  225.           users leave.
  226.  
  227.      The follow errors do not terminate immediately, though may cause
  228.      early termination, hence will return an exit code of 0.
  229.  
  230.      Warning -- Pattern limit xx reached. Aborting!
  231.  
  232.           If "xx" reads "128" then try using a smaller number for the
  233.           quantize fraction, otherwise try increasing the maximum number
  234.           of patterns (in configuration file - see above). A MOD file
  235.           will be created anyway, so at least you will have something.
  236.  
  237.  
  238. Andrew Scott
  239. INTERNET:ascott@tartarus.uwa.edu.au
  240.